=============
Contributions
=============

.. highlight:: none

Contributions are welcome, bug fixes and `SASL mechanisms`_ in particular.
If you want to contribute another feature, consider `filing a feature
request <https://github.com/odkr/sievemgr/issues/new>`_ first, so that we
can discuss things beforehand and you do not spend time working on a
patch that I may reject.


STYLE
=====

Please target Python version 3.9 and follow PEP8_, PEP20_, PEP257_ as well
as the spirit of Robert Pike's `Notes on Programing in C
<https://doc.cat-v.org/bell_labs/pikestyle>`_.


TESTING
=======

Call ``make check`` to run the test suite and ``make quickcheck`` to skip
slow tests. Set the `checks` macro to override which tests are run (e.g.,
``make checks=tests.test_acap``) and the ``sources`` macro to override
which files are tested (e.g., ``make sources=sievemgr.py check``). Your
code should pass ``make check``. It would be nice if you added tests, too.

Call ``make lint`` to run various linters, if they are installed, and
``make quicklint`` to only run Ruff_, MyPy_, Bandit_, and vermin_.


VERSION CONTROL
===============

SieveManager uses Git_ and follows the `Git Flow`_ branching model. The
source code is hosted at `Codeberg <https://codeberg.org/odkr/sievemgr>`_
(primary) and `NotABug <https://notabug.org/odkr/sievemgr>`_ (secondary).


PULL REQUESTS
=============

Fork SieveManager on Codeberg or NotABug.

Download the ``devel`` branch of your fork::

    git clone --branch devel "git@${HOST:?}:${USERNAME:?}/sievemgr.git"

Set up SieveManger as upstream source::

    git remote add upstream git@codeberg.org:odkr/sievemgr.git

Create a branch for your changes::

    git checkout -b feat-foo

Make your changes::

   vi sievemgr.py

Commit, rebase, and push::

    git add sievemgr.py
    git commit -S -m 'feat: added support for foo'
    git pull --rebase upstream devel
    git push origin feat-foo

.. important::
   Please sign your commits.

Finally, submit your pull request. 


PATCHES
=======

You can also send a patch to the :file:`@zoho.com`
address listed in my `PGP key`_.

Download the ``devel`` branch::

    git clone --branch devel "git@codeberg.org:odkr/sievemgr.git"

Set up SieveManger as upstream source::

    git remote add upstream git@codeberg.org:odkr/sievemgr.git

Create a branch for your changes::

    git checkout -b feat-foo

Make your changes::

   vi sievemgr.py

Commit and rebase::

    git add sievemgr.py
    git commit -S -m 'feat: added support for foo'
    git pull --rebase upstream devel

Create a patch::

    git diff HEAD HEAD~1 >foo.patch

